home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / man3 / ConfigWind.3 < prev    next >
Text File  |  1994-09-20  |  11KB  |  354 lines
  1. '\"
  2. '\" Copyright (c) 1990-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/ConfigWind.3,v 1.14 93/07/07 16:27:29 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tk_ConfigureWindow tkc 3.3
  206. .BS
  207. .SH NAME
  208. .na
  209. Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_SetWindowColormap, Tk_DefineCursor, Tk_UndefineCursor \- change window configuration or attributes
  210. .ad
  211. .SH SYNOPSIS
  212. .nf
  213. \fB#include <tk.h>\fR
  214. .sp
  215. \fBTk_ConfigureWindow\fR(\fItkwin, valueMask, valuePtr\fR)
  216. .sp
  217. \fBTk_MoveWindow\fR(\fItkwin, x, y\fR)
  218. .sp
  219. \fBTk_ResizeWindow\fR(\fItkwin, width, height\fR)
  220. .sp
  221. \fBTk_MoveResizeWindow\fR(\fItkwin, x,  y, width, height\fR)
  222. .sp
  223. \fBTk_SetWindowBorderWidth\fR(\fItkwin, borderWidth\fR)
  224. .sp
  225. \fBTk_ChangeWindowAttributes\fR(\fItkwin, valueMask, attsPtr\fR)
  226. .sp
  227. \fBTk_SetWindowBackground\fR(\fItkwin, pixel\fR)
  228. .sp
  229. \fBTk_SetWindowBackgroundPixmap\fR(\fItkwin, pixmap\fR)
  230. .sp
  231. \fBTk_SetWindowBorder\fR(\fItkwin, pixel\fR)
  232. .sp
  233. \fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR)
  234. .sp
  235. .VS
  236. \fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR)
  237. .sp
  238. \fBTk_DefineCursor\fR(\fItkwin, cursor\fR)
  239. .sp
  240. \fBTk_UndefineCursor\fR(\fItkwin\fR)
  241. .VE
  242. .SH ARGUMENTS
  243. .AS XSetWindowAttributes borderWidth
  244. .AP Tk_Window tkwin in
  245. Token for window.
  246. .AP "unsigned int" valueMask in
  247. OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR,
  248. indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use.
  249. .AP XWindowChanges *valuePtr in
  250. Points to a structure containing new values for the configuration
  251. parameters selected by \fIvalueMask\fR.  Fields not selected
  252. by \fIvalueMask\fR are ignored.
  253. .AP int x in
  254. New x-coordinate for \fItkwin\fR's top left pixel (including
  255. border, if any) within tkwin's parent.
  256. .AP int y in
  257. New y-coordinate for \fItkwin\fR's top left pixel (including
  258. border, if any) within tkwin's parent.
  259. .AP "unsigned int" width in
  260. New width for \fItkwin\fR (interior, not including border).
  261. .AP "unsigned int" height in
  262. New height for \fItkwin\fR (interior, not including border).
  263. .AP "unsigned int" borderWidth in
  264. New width for \fItkwin\fR's border.
  265. .AP XSetWindowAttributes *attsPtr in
  266. Points to a structure containing new values for the attributes
  267. given by the \fIvalueMask\fR argument.  Attributes not selected
  268. by \fIvalueMask\fR are ignored.
  269. .AP "unsigned long" pixel in
  270. New background or border color for window.
  271. .AP Pixmap pixmap in
  272. New pixmap to use for background or border of \fItkwin\fR.  WARNING:
  273. cannot necessarily be deleted immediately, as for Xlib calls.  See
  274. note below.
  275. .AP Colormap colormap in
  276. .VS
  277. New colormap to use for \fItkwin\fR.
  278. .AP Cursor cursor in
  279. New cursor to use for \fItkwin\fR.  If \fBNone\fR is specified, then
  280. \fItkwin\fR will not have its own cursor;  it will use the cursor
  281. of its parent.
  282. .VE
  283. .BE
  284.  
  285. .SH DESCRIPTION
  286. .PP
  287. These procedures are analogous to the X library procedures
  288. with similar names, such as \fBXConfigureWindow\fR.  Each
  289. one of the above procedures calls the corresponding X procedure
  290. and also saves the configuration information in Tk's local
  291. structure for the window.  This allows the information to
  292. be retrieved quickly by the application (using macros such
  293. as \fBTk_X\fR and \fBTk_Height\fR) without having to contact
  294. the X server.  In addition, if no X window has actually been
  295. created for \fItkwin\fR yet, these procedures do not issue
  296. X operations or cause event handlers to be invoked;  they save
  297. the information in Tk's local
  298. structure for the window;  when the window is created later,
  299. the saved information will be used to configure the window.
  300. .PP
  301. See the X library documentation for details on what these
  302. procedures do and how they use their arguments.
  303. .PP
  304. In the procedures \fBTk_ConfigureWindow\fR, \fBTk_MoveWindow\fR,
  305. \fBTk_ResizeWindow\fR, \fBTk_MoveResizeWindow\fR, and
  306. \fBTk_SetWindowBorderWidth\fR,
  307. if \fItkwin\fR is an internal window then event handlers interested
  308. in configure events are invoked immediately, before the procedure
  309. returns.  If \fItkwin\fR isn't a top-level window
  310. then the event handlers will be invoked later, after X has seen
  311. the request and returned an event for it.
  312. .PP
  313. Applications using Tk should never call procedures like
  314. \fBXConfigureWindow\fR directly;  they should always use the
  315. corresponding Tk procedures.
  316. .PP
  317. .VS
  318. The size and location of a window should only be modified by the
  319. appropriate geometry manager for that window and never by a window
  320. itself (but see \fBTk_MoveToplevelWindow\fR for moving a top-level
  321. window).
  322. .VE
  323. .PP
  324. .VS
  325. It is not allowable to use \fBTk_ConfigureWindow\fR to change the
  326. stacking order of a window (\fIvalueMask\fR may not contain the
  327. \fBCWSibling\fR or \fBCWStackMode\fR bits).
  328. To change the stacking order, use the procedure \fBTk_RestackWindow\fR.
  329. .VE
  330.  
  331. .SH BUGS
  332. .PP
  333. \fBTk_SetWindowBackgroundPixmap\fR and \fBTk_SetWindowBorderPixmap\fR
  334. differ slightly from their Xlib counterparts in that the \fIpixmap\fR
  335. argument may not necessarily be deleted immediately after calling
  336. one of these procedures.  This is because \fItkwin\fR's window
  337. may not exist yet at the time of the call, in which case \fIpixmap\fR
  338. is merely saved and used later when \fItkwin\fR's window is actually
  339. created.  If you wish to delete \fIpixmap\fR, then call
  340. \fBTk_MakeWindowExist\fR first to be sure that \fItkwin\fR's window exists
  341. and \fIpixmap\fR has been passed to the X server.
  342. .PP
  343. .VS
  344. A similar problem occurs for the \fIcursor\fR argument passed to
  345. \fBTk_DefineCursor\fR.  The solution is the same as for pixmaps above:
  346. call \fBTk_MakeWindowExist\fR before freeing the cursor.
  347. .VE
  348.  
  349. .SH "SEE ALSO"
  350. Tk_MoveToplevelWindow, Tk_RestackWindow
  351.  
  352. .SH KEYWORDS
  353. attributes, border, color, configure, height, pixel, pixmap, width, window, x, y
  354.